You may use this program for 30 days for evaluation purposes. After 30 days, if you continue using it, you are required to send $10 to:
Bob Blaylock
580 Pintura Drive
Santa Barbara, California, 93111
This program may be distributed freely, subject to the following conditions:
The accompanying documentation file, QWK.doc, must be distributed with it.
This program may not, under any circumstances, be uploaded to, or distributed by, Compuserve Information services.
I, Bob Blaylock, claim the exclusive right to control the distribution and use of this program. No copyrights other than mine may be claimed on this program, either by itself, or as part of a collective work, and no restrictions may be placed upon the distribution of this program by anyone other than myself.
The latest version of this package will always be available on the Bowhead Whale BBS, at (805)964-UNIX, in the Macintosh: room. This is definitely the best place to get a current version. I always upload new revisions there, and they become available immediately for downloading.
I also sometimes upload copies of this to America OnLine, and to GEnie. However, due to the slowness of uploading to AOL at 2400 bps, and the almost unbearable slowness of uploading anything to GEnie, I do not upload there nearly as often as I do to the Bowhead Whale. Also, there is a delay, often of several days, from the time I upload to GEnie or AOL and the time that they actually make it available for downloading. Very often, the version I upload to AOL or GEnie is obsolete by the time they make it available.
On America OnLine, there is often a delay of several days from the time I upload a file, to the time they make it available for downloading. Also, the staff at AOL have offered considerable resistance to accepting and posting updates to this program as often as I have been uploading them. As a result, if you got this software off of AOL, there's a very good chance that the version you have is badly outdated. If this matters to you, then I suggest you give the Bowhead Whale a call, and check the version that is posted there. The copy of this program that is on the Bowhead Whale is nearly always the current one, as I nearly always post new versions there as soon as I can after creating them.
I can be contacted for bug reports, suggestions, etc., as “Bob Blaylock” on the Bowhead Whale BBS. To send me private messages, just enter them there in the Mail> room.
I can also be contacted at these other addresses:
America OnLine: TheBob
GEnie: B.BLAYLOCK
InterNet: TheBob@aol.com
You can, of course, also send me old-fashioned mail at the above postal address.
You should have received the following files in this archive:
QWK The QWK message reader
QWK.doc This document that you're reading now.
REP The program to create .REP packets from your reply messages.
PC.font An IBM-compatible bitmapped font, in which to read your messages.
Anyway, QWK is a simple offline message reader. Many BBSes allow you the option, instead of reading messages while you are logged in, typing up the phone lines, and (in the case of long-distance calls) racking up phone charges, of having all your new messages gathered into a .QWK packet, which you then download, and read offline.
Anyway, I suppose now you want me to tell you how to use this program, right?
Well, to start with, you need to download a .QWK packet from your BBS. This procedure varies greatly from one BBS to another; if you can't figure it out, you'll have to ask your sysop for help.
In every instance I have seen so far, the .QWK packets have arrived compressed with PKZIP. You will, therefore, need an unZIPping program to run on your Macintosh. I know of several. StuffIt Deluxe, includes an UnZIPper. There are also a number of minor shareware and freeware programs out there. Names I know of are unZip, and ZipPop. You should be able to find one of these, at least, on a BBS near you, probably from the same place you downloaded QWK.
Anyway, make sure that whatever unZIPper you use, you have it configured so that it does not attempt to strip linefeeds, or otherwise convert the files it extracts.
You will find that a .QWK packet contains a large number of files. The two files that QWK wants are called “MESSAGES.DAT” and “CONTROL.DAT”. CONTROL.DAT is optional; QWK uses it to build a list of the conference names. If QWK doesn't find CONTROL.DAT, it will still process the MESSAGES.DAT file correctly, but you will only see the numbers, not the names of the conferences in which the messages are found. If the BBS from which you obtained the .QWK packet has a really large number of conferences, you might want to omit the CONTROL.DAT file, as it does take some time to process it and build the conference list.
Now that you have the MESSAGES.DAT, and possibly the CONTROL.DAT files extracted, you're ready to run QWK. When you run it, you'll be presented right away with a dialog, containing copyright information, a picture of me, and the instruction to select the MESSAGES.DAT file at the next dialog. Clicking almost anywhere in this dialog will dismiss it, and present you with the standard SFGetFile() dialog. At this point, use this dialog to select the MESSAGES.DAT file from the .QWK packet you want to read. (Actually, the program currently discards the selected file name, and only uses the directory selected by this dialog. If you select any file that is in the same directory as the MESSAGES.DAT file, it will look there for a file named “MESSAGES.DAT”, and also for one in the same directory named “CONTROL.DAT”. I may change this in the future, but for now, this way seemed to make sense to me.)
Next, you'll be presented with another dialog, which asks you how to deal with IBM-specific characters, and what Creator signature to assign to the converted message file.
You are given three options for dealing with IBM-specific characters. The first is to leave them as they are. If you have an IBM-compatible font that you can use to view the converted messages, then this is the best option. In fact, I've decided to include just such a font in the archive I'm going to use to distribute this program.
The second is to attempt to convert as many of them as possible to the corresponding Macintosh characters. There are, however, many IBM-specific characters that have no corresponding Macintosh characters. The small text field at the end of the third option specifies a character to use in place of those characters which cannot be otherwise converted.
The third option is to convert all IBM-specific characters to the character entered into the small text field.
The other thing this dialog asks you for is the Creator signature to give the converted message file. This currently defaults to ‘R*ch’, which is the signature for BBEdit. This means that when you double-click on the converted message file, BBEdit will be invoked as the standard program to view it with. If you have a different text editor program that you wish to use, you may enter the Creator signature for that program in this space. Some known signatures are:
‘ttxt’ TeachText
‘Edit’ Consulair's Edit program, or the newer clone, Edit II
‘R*ch’ BBEdit 2.2 or newer
‘Rich’ BBEdit (older than 2.2)
‘MSWD’ MicroSoft Word
‘MACA’ MacWrite
‘KAHL’ Think C
Once you've dismissed this dialog, you'll get a standard SFPutFile() dialog, asking you where to save the converted message text I'm not sure what there is to say about this that isn't obvious. You simply use this to tell QWK where to save the converted messages.
After you dismiss this final dialog, you'll be presented with a simple window telling you that the program's doing its thing. How long it takes may vary greatly, depending on the size the of the packet, and how fast a machine you have. When it's finished, the program will quietly exit back to the Finder. At this point, if you look where you told it to save the output, you'll find a text file. Reading this text file, you'll find first my copyright notice again, and then the text of all the messages in the packet.
The recommended procedure from this point is as follows:
Load your converted message file into one window of a text editor. Scroll through this file to read your messages.
In another window of the same, or a different text editor, enter your replies, in the format used by REP. (See below.)
When you are finished, save the text file in which you have been entering your replies, and run REP to convert it into a .REP packet.
How to use REP
-------------
REP is currently in a very crude form. When it is run, you'll be presented with Think C's generic ccommand() dialog. When you see this dialog, click on the radio button labeled “file” near the left side of the dialog, under the header that reads “Standard Input”. You will then be presented with the standard GetFile dialog. Use this dialog to select the text file in which you have saved your replies.
QWK was modified slightly, to go along with REP. As of version 1.20 of QWK, the header format is slightly different, so that the header now easily provides the information needed by REP's +++REPLY command. If you use REP with an earlier version of QWK than 1.20, then the headers will not be in the format expected by +++REPLY. I strongly suggest that you always use REP only with the version of QWK that comes packaged with it. I reserve the right to make changes in the future to the header format, but if I do, I will keep the matching version of REP set to read the header.
When you are then returned to the previous dialog, click on the “OK” button. REP will then process this file, and place the output, in the same directory as the input file, in a file that is named the same as the BBS ID (I'll explain this shortly), with the extension “.MSG” appended to it, and another, similarly-named, but with the extension “.REP”.
To post your replies on the BBS, upload the .REP file into that BBS' mail door. If you have a PKZIP-compatible archiving utility, you may use it to archive the .MSG file. If you do this, you should give the archive the same name as the .REP file (which means you gotta get rid of the .REP file that REP just created). The advantage of this is that a proper ZIP utility should actually compress the data, so that the resulting .REP file should be considerably smaller. This could make a difference if you have a very large reply packet, and the BBS you wish to upload it to is a long-distance call, or a system which charges for connect time. The .REP file created by REP is in PKZIP format, but it is not compressed in any way.
The text file used as input by REP has the following structure…
The first line must contain your name, as used on that BBS. I guess this is simple enough that I don't need to explain any further. Later versions of this program will probably read this out of the CONTROL.DAT file. In fact, if you should forget your name, you can find it on the seventh line in CONTROL.DAT.
The second line contains the BBS ID of the BBS for which you are generating replies. Every BBS that uses a .QWK mail door has some short ID string, no more than eight characters. When you download a packet from this BBS, it will probably be named as this string with “.QWK” appended to it. However, it is possible for this packet to be named otherwise. You can find the BBS ID of the system that generated a .QWK packet by looking in the CONTROL.DAT file. In fact, future versions of this software will probably do so, eliminating the need for you to fuss with this. The BBS ID is found on the fifth line in CONTROL.DAT, separated by a comma from a number that you don't need to worry about.
QWK now includes the BBS ID in its output. Look just after the copyright notice, and before the first message.
The remainder of the file is to consist of commands and message text. Commands are distinguished by having three plus signs prepended to them. Any line of text which does not begin with “+++” is processed into the currently open message. If there is no open message, then non-command text is ignored.
That's a bit confusing, I suppose. Well, after I tell you the few really important commands, I'll explain this a bit more clearly.
+++NEW This command opens a new message in your reply packet. This is best used to create new messages, which are not replies to existing messages. After a +++NEW command, you should always use the +++CONFERENCE:, +++TO:, and +++SUBJECT: commands (which I'll explain later) to specify where the message should go, to whom it is addressed, and what the subject of the message should be.
After a +++NEW command is given, all non-command text up to the next +++END, +++NEW, or +++REPLY command, or to the end of the file, will be placed in this message.
+++END This command closes the current message. After this command is give, any non-command text will be discarded, until another +++NEW or +++REPLY command is found.
+++REPLY This command is used to create a reply to a message out of your .QWK packet. Immediately after this command, you should paste the message header from the message out of the text file that was created by QWK. This command reads in that header, and uses it to generate the information that directs the reply to the correct forum, and recipient.
Here's an example of a text file for REP, which generates one new message, and one reply to an existing message:
----------------------- Cut Here -----------------------
Bob Blaylock
BHWHALE
+++New
+++Conference: 10
+++To: Joe Blow
+++Subject: Test Message
This is a test message. It will be directed to the user named "Jow Blow", in conference #10.
+++End
+++Reply
Conference 20: Test Messages
Message: 20/1000 07-21-92 13:26
Status:- Public, Received
To: JANE PAINE
From: JANOS SZAMOSFALVI
Subject: Test Messages...
Reply to: 987
This message is a reply to message 1000 in conference #20. Since message 1000 was written by JANOS SZAMOSFALVI, thats who this reply will be directed to. The reply, like the original message, will have "Test Messages..." as its subject, and will be designated as a reply to 1000.
+++End
----------------------- Cut Here -----------------------
There, that's not so bad, is it? Now, here's a list of all the commands.
+++COMMENT
This command causes the current message to be designated as a comment to the sysop. This command does not, however, fill in the To: field; you should still do so using the +++To: command. I'm not entirely certain how this message type is handled by mail doors. Use it at your own risk.
+++CONFERENCE: <number>
This command is used to specify which conference the message will be posted in. Conferences are referenced only by number at this time. For example, to post the current message in conference #30, you'd use this command:
+++Conference: 30
The parameter of this command, like those of all commands that take parameters, must be separated from the command by at least one space.
+++ECHO
This command sets the message to be an "Echo" message. This is the default condition. An Echo message will, if it is posted in a conference that is networked, be sent over the network. See also: +++NOECHO
+++END
This command, as alread mentioned, is used to close the current message.
+++FROM: <name>
This command changes the name that is in the From: field of the message. At this writing, I still do not know how useful this command will really be. My assumption is that if you use this command on a message in a forum which allows aliases, that this will cause that message to be posted as being "From" the name that is given as an argument to this command, instead of using your own name. I would assume that except where such aliasing is allowed, most BBSes probably put your name on the message, regardles of what you put in the From: field.
For example, if, instead of bearing your own name, you wish the message to appear to be from "Slick Willie", you'd use this command in the message.
+++From: Slick Willie
I've tried using this command once now, on a BBS that allows handles in some of its conferences. Even in a conference that otherwise allows handles, it silently rejected the message I tried to upload with the altered From: field. No warning or anything. Just that I knew the packet had four messages in it, and when I uploaded it, the BBS reported that it had accepted and posted three. If you use this command, use it at your own risk.
+++GROUP: <password>
This command sets the message to have the status of being "Group Password". I don't really know what this means, but it's one of the modes described by the documents I have on the .QWK format, so I figured I should support it. The <password> parameter will be stored in the message's Password field.
+++LITERAL
Use this command if you need to include a line in one of your messages which starts with +++. The +++Literal command tells REP to interpret the next line as message text, and not as a command, even if it starts with +++.
+++NEW
This command creates a new, non-reply message. You should always follow this command with a +++Conference:, a +++To:, and a +++Subject: command.
+++NOECHO
This command makes the current message a non-echo message. This means that if posted in a networked conference, it will not be sent over the network, but will be readible only on the BBS where you posted it.
+++PASSWORD: <password>
This makes the current message a password-protected message, using the password that is specified in the argument to this command.
+++PRIVATE
This makes the current message a private message, readible only by you, and the person to whom it is addressed.
+++PUBLIC
This makes the current message a public message, readible by all. This is the default mode, unless you are replying to a private message.
+++REPLY
This opens a new message, which is to be a reply to an existing message out of your .QWK packet. Immediately after this command, you must paste the message header from the message to which you are replying.
+++SUBJECT: <text>
This command specifies the text that will go into the current message's Subject: field.
+++TO: <name>
This specifies the name of the person to whom the current message is addressed.
+++TYPE: <type>
The +++Type command is to be separated from its argument by exactly one space; no more. Starting at the first character after the space, the next four characters are used as the argument.
This command sets the Type attribute which the final .REP file will be given. By default, it is given the type of 'TEXT', which designates it as a text file. This is because most terminal programs know, when uploading a 'TEXT' file, not to use the MacBinary protocol, which would mess up any attempts by the non-Macintosh host on the other end to process this file.
A possible problem is that most terminal programs can also be set to perform an end-of-line marker translating on text files. This translation will also screw up the .REP file, if it is applied.
I recommend that you set your terminal program not to perform any EOL translation on text files, and leave the +++Type setting at its default value. However, if you must have your terminal set to perform any translation on text files, then you can use this command to designate a type other than 'TEXT' for the .REP file. You must then make sure that your terminal program is configured in such a way that it will not perform MacBinary encoding, or any other translation upon files of the type you have designated.
Example: To designate 'zBin' as the type to be used for .REP files:
+++Type: zBin
Note that types are case-sensitive. Note also that there must be exactly one space between the command and the type argument.
+++WRAP: <number>
This command specifies the maximum line length to allow in messages. If you enter lines longer than <number> characters, then REP will automatically wrap them to fit within the specified length. The default setting is to wrap lines at 79 characters. To disable wrapping entirely, use this command with no argument, or with zero or a negative number as the argument.
***
Recent important revisions:
1.30 I had QWK crash on me tonight (02/17/93) while I was decoding a packet that I had downloaded from the ZyXEL BBS. It turned out that the MESSAGES.DAT file was padded at the end with a block containing mostly bytes with the value 0xFF. QWK already knew to disregard blocks at the end which were all zero, but this was something new. QWK now checks the Number, Ref, and Blocks field of what it thinks to be a message header, and if it finds any bytes outside of the range 0x20 to 0x7F in any of these fields, it disregards that block as if it were all zero.
1.29 REP now displays, with each error message, the number of the offending line.
1.28 Added automatic text wrapping to REP, along with the +++Wrap: command to control it.
1.27 Added the +++Comment command to REP.
1.26 Added the +++Literal command to REP.
1.25 The QWKLAY13.ZIP file, which I had been using as a reference on the QWK/REP format, apparently contains an error. As a result, private messages were not being handled correctly. This has now been fixed. (QWKLAY13.ZIP claims that the flag field should be '+' for a private, unread message, and '*' for a private, read message. This is apparently backwards. It appears that it should be '*' for private, unread, and '+' for private, read.)
1.24 Several bugs that were discovered in 1.23 were corrected.
1.23 REP now outputs a PKUNZIP-compatible .REP file. This eliminates the need for a separate ZIP utility to archive the .MSG file. I was really glad to get this feature implemented, because the only ZIP utility I know of for the Macintosh is rather buggy.
1.22 Since I have been developing, testing, and using this package on a 68020-based Macintosh II, I was completely unaware, until a friend called my attention to it, that QWK contained a bug which caused it to crash on 68000-based machines. This version fixes it.
1.20 Added a new program, REP, to collect messages, and place them into a .MSG file which may be archived using a ZIP utility, into a .REP file for uploading.
***
Future plans:
REP is still very crude, implemented as a generic C filter-type program. The next significant change I wanna make to this package, is to put a more Macintosh-like user interface on REP similar to that which QWK currently has.
In the long term, what I eventually wanna do with this package is combine QWK and REP into one program, together with a built-in viewer for the incoming messages, and a built-in editor for creating and editing outgoing messages. Perhaps the editor will include some special feature to make it easier to enter IBM-specific characters into messages.
What about taglines? Most QWK packages include a feature for adding taglines automatically at the end of every outgoing message. I've always regarded this as tacky, and as a less-than-fully-ethical way to turn every customer into an unwilling advertiser. If I get enough response from people telling me they want taglines, perhaps I'll eventually add such a capability. If I do, it WILL be optional, and the default setting will be to not use them.
***
Life's Hard Lesson Number 7,254: On a 68020 or better, if you have a pointer to a 32-bit value, you can dereference it, no matter what value it has, so long as it points to a valid memory location. On a 68000, this pointer must contain an even value; if it contains an odd value, then when you dereference, the program crashes with an Address Error.
I've been developing QWK through several versions, on my 68020-based Macintosh II, blissfully unaware of the fact that what seemed to me like a perfectly good way of transferring a Creator string from a Pascal-type string to a variable of the OSType type, which is essentially a 32-bit integer, was causing this program to be unusable on all 68000-based Macintoshes.
Just for reference's sake, the following code is NOT a good way to perform this action:
{
OSType *OSptr,Creator;
Str255 string;
.
.
.
OSptr = (void *)string + 1;
Creator = *OSptr; /* If string is at an even address, then OSptr will contain an odd address, which will cause 68000-based machines to crash when they try to execute this instruction. */
